/*
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

/*
 *
 *
 *
 *
 *
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util.concurrent;


/**
 * 异步计算的结果。
 * 该接口提供了方法:
 *       1、检查计算是否完成
 *       2、取消计算
 *       3、获取计算结果 - get()方法,这可能会阻塞,直到结果可用
 * 注意: 如果计算已经被取消或出现异常，get方法将抛出相应的异常。
 */
public interface Future<V> {

    /**
     * 尝试取消当前正在进行的计算。
     * @param mayInterruptIfRunning 如果设置true  尝试取消任务时，如果任务正在运行，它将被中断
     *                              如果设置false 不会中断正在运行的任务，但仍然会取消等待执行的任务
     * {@return false} 如果任务已经完成、已经取消或者由于某些其他原因无法取消
     * {@return true } 成功取消任务
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     * 检查当前任务是否已被取消。
     * 任务可以在执行过程中被取消，或者在调用cancel方法后被取消。
     * @return 如果任务已经被取消，则返回true；否则返回false。
     */
    boolean isCancelled();

    /**
     * 检查当前任务是否已经完成。
     * 任务完成意味着它已经成功执行、被取消或抛出异常。
     * @return 如果任务已经完成，则返回true；否则返回false。
     */
    boolean isDone();

    /**
     * 等待并返回任务的计算结果。
     *   1、如果任务尚未完成，此方法将阻塞，直到结果可用。
     *   2、如果任务由于执行异常而完成，则抛出ExecutionException。
     *   3、如果任务被取消，则抛出CancellationException。
     * @return 任务的计算结果。
     * @throws InterruptedException 如果当前线程在等待结果时被中断。
     * @throws ExecutionException   如果任务由于执行异常而完成。
     */
    V get() throws InterruptedException, ExecutionException;

    /**
     * 等待并返回任务的计算结果，但最多只等待指定的时间。
     * 如果在指定的时间内任务完成，则返回结果；否则抛出TimeoutException。
     * 如果任务由于执行异常而完成，则抛出ExecutionException。
     * 如果任务被取消，则抛出CancellationException。
     *
     * @param timeout 等待结果的最大时间。
     * @param unit    时间单位。
     * @return 任务的计算结果。
     * @throws InterruptedException 如果当前线程在等待结果时被中断。
     * @throws ExecutionException   如果任务由于执行异常而完成。
     * @throws TimeoutException     如果等待结果的时间超过指定的超时时间。
     */
    V get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException;
}

